Extension::CurlRequestTemplate Method
Syntax
.RequestTemplate as Extension::CurlResponse (request as C | request as P, C namedResource [, variables as C | variables as P [, args as SQL::Arguments]])
Arguments
- requestCharacter Pointer
Request defined as a JSON string or dot variable. Variable placeholders and SQL::Arguments can be used in the request definition. Variables use bracket syntax {variableName} and are specified in the variables parameter. SQL::Arguments are specified using colon syntax :variableName and are specified in the args parameter.
Special placeholders are also available for the namedResource:
- Placeholder
- Description
- {namedresource.access_token}
The access token that was retrieved when the authentication, defined in the Named Resource, was performed.
- {namedresource.resourceURL}
The base URL for the request as returned by the service when the authentication, defined in the Named Resource, was performed.
The request must have the following structure:
- uristring
The request URI. See examples below for more information.
- formobject
Required if the URI endpoint requires data submitted in a form format.
An object containing one or more properties that define data to submit in the request. Refer to the API documentation for the request endpoint for what data can be submitted.
- bodyobjectstring
Required if the URI endpoint requires data submitted in the body of the request.
An object or string containing the body of the request. Refer to the API documentation for the request endpoint for format requirements for data submitted in the body.
- headersobject
An object containing headers to include in the request. Required if required by the request endpoint.
- authobject
This property is required if the URI requires authentication. Authentication can be one of two types: username (user) and password (pass) or a bearer token (bearer), either from a Named Resource or generated using other means (examples below).
- bearerstring
Required if authentication uses a bearer token. Can use the special placeholder, {namedresource.access_token}, to get the token from the Named Resource provider (specified by the namedResource argument).
- userstring
Required if authentication uses a user name and password. The authentication user name.
- passstring
Required if authentication uses a user name and password. The authentication password.
- namedResourceCharacter
A Named Resource. The Named Resource can contain information for authentication (such as authentication information for Salesforce or Google.) Named Resources are defined in Project Properties on the Web Projects Control Panel.
- variablesCharacter Pointer
Default = null_value(). Defines values for variables used in the request. Can be specified as a dot variable, a JSON string, or one or more URI encoded name-value pairs in the format "variable_name=value" joined with an ampersand (&). E.g. "var1=value1&var2=value2". Required if request uses variables.
- argsSQL::Arguments
Default = null_value(). A SQL::Arguments object that defines arguments used in the request. Required if request uses SQL::Arguments.
Returns
- responseExtension::CurlResponse
The response returned by the call.
Description
Simple CURL request template, populated from optional named resource, variables and arguments, from request JSON or supplied properties.
When defining the URI and the headers in the JSON passed to the extension::curl::RequestTemplate() method, there are two special placeholders that you can use:
- {namedresource.access_token} - the access token that was retrieved when the authentication, defined in the Named Resource, was performed
- {namedresource.resourceURL} - the base URL for the request as returned by the service when the authentication, defined in the Named Resource, was performed.
The values for these placeholders are resolved by the specified Named Provider (see the namedResource variable in the example code below).
Sample Xbasic code showing how a REST API call is made to the Salesforce API.
(Assume that the authentication details for the Salesforce account have been saved in a Named Provider called salesforcetoken. )
Notice that the URI specified in the JSON string has an argument name in it (:id)
dim json as c = <<%json% { "uri": "{namedresource.resourceurl}/services/data/v39.0/sobjects/Account/:id", "auth": { "bearer" : "{namedresource.access_token}" } } %json% dim namedResource as c = "salesforcetoken" 'define the value of the arguments used in the URI dim args as sql::arguments args.add("id","0011N00001EBYRDQA5") 'instead of putting the account id in a sql::argument, we could have 'used a variable and referenced the variable in the URI as {accountNumber) 'instead of :id 'for example: /services/data/v39.0/sobjects/Account/{accountNumber} dim vars as p vars.accountNumber = "0011N00001EBYRDQA5" dim response as extension::CurlResponse response = extension::curl::RequestTemplate(json,namedResource,vars,args) if response.content <> "" then dim json as c json = response.content else 'no response end
Post Commands
Posting data with a simple body, like JSON, requires populating a "body" property.
Below is an example appending a range of values to a google sheet.
dim json as c = <<%json% { "uri": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetid}/values/{SheetName}!A1:D1:append?valueInputOption=USER_ENTERED", "body": { "range": "{SheetName}!A1:D1", "majorDimension": "ROWS", "values": [ [ "=ROW()-1" , "sam", "smith", "smithco"] ] }, "auth" : { "bearer" : "{namedresource.access_token}" }, "headers" : { "Content-Type" : "application/json" } } %json% dim namedResource as c = "GoogleSheet" dim vars as p dim vars.spreadsheetid as c = speadsheetId dim vars.SheetName as c = "Customers" dim args as sql::arguments dim response as extension::CurlResponse response = extension::curl::RequestTemplate(json,namedResource,vars,args) end
Multipart Forms
Posting data to a multipart form requires defining a 'form' property with an object that has user supplied names (to tag the items) and sub properties of either body (for embedded content), or filename (for files stored on disk to upload).
Both body and filename form 'parts' can include optional content length and content type. content-length of 'length' will calculate the length from the supplied input.
Below is an example of uploading a file to google drive.
dim json as c = <<%json% { "uri": "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart", "form" : { "metadata" : { "body" : { "name" : "{remoteName}" , "parents" : [ "{folderId}" ] }, "content-length" : "length" } , "media" : { "filename" : "{localname}" , "Content-Type" : "{mimetype}" } }, "auth" : { "bearer" : "{namedresource.access_token}" } } %json% dim vars as p dim vars.folderId as c = folderId dim vars.remoteName as c = file.filename_parse(filename,"ne") dim vars.localname as c = strtran(filename,chr(92),"/") dim vars.mimetype as c = resolve_mime_type(file.filename_parse(filename,"e")) dim args as sql::arguments dim response as extension::curlresponse response = extension::curl::RequestTemplate(json,namedResource,vars,args) end